Loadstar 248/248.d81/t.db+ doc 3

Text File | 2004-01-01 | 13.6 KB | 542 lines

u
            DOTBASIC PLUS
               Part III
     by Dave Moorman & Lee Novak


    Never again must you fight for
string space in your text adventures
and other programs. With the following
commands, you can put your lines of
text in a Edstar file (Edstar is our
nifty text editor that produces 38-
column lines of text), use .BL0 to
bload it into memory (under ROM), the
use RACK (.RK) to turn the text into a
virtual string array. RACK INDEX (.RI)
will put any line into W$ for use in
your program. Here is a simple
example:

 100 .BL0,"T.DISKOVER",D,40960
 110 .RK,40960
 120 FOR X = 1 TO N%
 130 .RI,X
 140 PRINT W$
 150 NEXT


  RACK EDSTAR FILE
  ----------------
    Include: .RK
  .RK,LOCATION

    This routine takes an EDSTAR file
(terminated by a zero) and "racks it
up". A table of pointers is created
right after the zero at the end of the
text, enabling you to use .RI or .PRI
to grab or print individual lines of
the file.

    The file can be located anywhere
in memory, even under I/O. Racking
needs 3 bytes per line at the end of
the file for its pointers. The total
number of items is returned in N%.


  INDEX ITEM
  ----------
    Include: .RI
  .RI,INDEX#

    Once you've racked up an EDSTAR
file, you can index it. The indexed
item is returned in W$. F$ is also set
by indexing, and will always return a
null unless you happen to be looking
at a directory, in which case it
contains the entry's filename.


  PRINT ITEM
  ----------
    Include: .PRI
  .PRI,X,Y,INDEX#

    This routine indexes an item and
prints it anywhere on the screen. The
string is NOT returned in W$ or F$.


  PRINT FILENAME
  ----------
    Include: .PRFILE
  .PRFILE,X,Y,INDEX#

    If you've used GET DIRECTORY and
have racked up the resulting text, you
can immediately print the filenames.


  DEFINE REGION TEXT
  ------------------
    Include: .DRTEXT
  .DRTEXT,NUMBER,"STATIC STRING"

    The concept of "region text" for
LOADSTAR programs is credited to both
Jeff Jones and myself. CASH FLOWER (LS
#161) and QUICKSMITH (LS #164) both
used the concept, and it's interesting
to note that neither of us knew what
the other was up to.

    "Region text" is when the user
moves the mouse pointer around the
screen, and a message bar at the
bottom of the screen informs the user
of what will happen if he or she
clicks on that particular area. These
strings don't have to be associated
with regions - it's just likely that
this will be their most common use.

   Related Variables:     (& defaults)

  MV+20  Region Text Zone (LB)     (0)
  MV+21  Region Text Zone (HB)     (4)
  MV+22  Region Text Color / Flags (1)
  MV+23  Region Text Row          (24)

    Strings defined as region text
must NOT be made by combining smaller
strings. The string's POINTER will be
stored in its proper slot in the
Region Text Zone. Be sure this zone is
safe from BASIC and other data We
suggest the area in pages 46-55. The
Zone will never exceed 3 pages.

    All region text will be printed in
MV+22's color. Add 128 to MV+22 for
REVERSE printing. (Adding 64 changes
the way the pointers are stored and is
most useful from ML.)

    Add 32 to MV+22 and all your
region text will be CENTERED. Add 16
instead, and each string will be
printed after a forced leading SPACE.


  EDSTAR TO REGION TEXT
  ---------------------
    Include: .EDRTEXT
  .EDRTEXT,LOCATION

    This command defines ALL region
text with a single command! It takes
an EDSTAR file (terminated by 0),
racks it up, and POKEs MV+24 and
MV+25. The number of lines in the file
is returned in N%.

    Keep in mind that the FIRST line
of the EDSTAR file will be referenced
by number zero. You can have as many
lines as you want.


  PRINT REGION TEXT
  -----------------
    Include: .PRTEXT
  .PRTEXT,INDEX

    This prints region text on the
line specified in MV+23. It fills up
the unused part of the line with
spaces, so you don't have to worry
about erasing the old text before
printing over it. The string will be
printed as specified in MV+22, above.
Usually the "index" will be RG%, but
it doesn't have to be.

    Here is a simple example:

 100 .BL0,"TEXTFILE",D,40960
 110 .EDRTEXT,40960
 200 .DO:.MA
 210 .PRTEXT,RG%
 220 .UN CR%


  PRINT MESSAGE
  -------------
    Include: .MSG
  .MSG,COLOR,STRING

    This command prints your string
just like region text. You provide the
color, and MV+22 specifies the reverse
state, centering, or the leading
space. This command is useful for
special prompts and messages. The plus
"+" can be used to concatenate strings
printed by this routine.


  GET DIRECTORY
  -------------
    Include: .DIR
  .DIR,"$:*",D,LOC,#FILENAMES

    This will read the disk directory
from device D. The directory can be
placed anywhere, even under I/O. DB+
converts the directory to an EDSTAR
file as it is brought in. This allows
SCROLLING MENU to use the information
as a file requestor.

    Normally you would use "$:*" to
get all the disk's filenames. You can
replace "$:*" with any search pattern
you want, up to 16 characters long.
For example, using "$:b.*,p.*" on a
LOADSTAR disk (using a real C-64 or
True Drive in VICE) would bring in the
names of all the boot and text files.

    E$ will return the error message.
T$ will contain the disk's name within
quotes, and B$ will contain the
"blocks free" message. Use VAL(B$) to
extract the number of blocks free on
the disk. N% returns the number of
filenames loaded.

    If there was an error during the
directory getting, T$ and B$ will
return strings full of spaces, and E$
will tell about the error. The one
thing your program should do before
disk access is check if the drive is
actually online, like this:

   1000 close2:open2,dv,2:close2
   1010 if st=-128 then...
   1020 ...continue

    Line 1010 would go and deal with a
"device not present" situation. If all
is well, line 1020 executes and disk
access occurs.

    GET DIRECTORY has been greatly
improved with the addition of one more
parameter: how many filenames you have
room to hold. This number should be
calculated as:

   # files = INT((bufferspace-1)/32)

     For example, if your buffer was
from 49152 to 53248, you could fit
INT((4096-1)/32) = 127 names there.
This formula takes into account the
zero cap and the three bytes per line
that the racking process needs.

    If the buffer space is filled up
before all the filenames are loaded,
B$ will return "more files on disk".
If you don't care about buffer space,
use 0 for the number of filenames.

    A good place to put your directory
information is in pages 224+. You
easily put 250 filenames in this area
under ROM.


  SCROLLING MENU
  --------------
    Include: .SCMENU
  .SCMENU,X,Y,W,H,B,I,UN,HI,LOC,T$,B$

    For this command to work, you must
have an EDSTAR file in memory, and it
must end with a zero byte OR use .DIR
to get the directory.

    The X,Y,W,H parameters set the
area the menu will occupy. H must be
at least 7 characters tall and W 11
wide. B is the color of the menu box.
The unhighlighted items of the menu
are color UN. HI is the highlight bar
color. If you don't want the text to
reverse or un-reverse as the bar
moves, add 128 to HI.

    I is the color of the four words
in the corners of the menu: HOME, UP,
DOWN, and QUIT. Left-click on UP or
DOWN to scroll the text. Right-click
on them and the list jumps a page at a
time. The user can use the CRSR keys
to scroll or page through the text as
well.

    Clicking on HOME will bring the
list to the top. Pressing the HOME key
will bring the highlight bar to the
top of the page, and the next press
brings the list to the top.

    Click on an item or press RETURN
to select it. The entire item is
returned in W$. F$ will return a null
unless this is a file requestor - in
which case it contains the filename.
SL% returns the selection number.

    Clicking on QUIT, pressing Q, or
pressing the Global Escape key will
return zero in SL% and nulls in W$ and
F$.

    LOC is the location of the EDSTAR
file, which can be anywhere in memory.
The file will be "racked up" before
use, which can take up to a second
(gasp!) on 1 MHz machines. For already
racked data, put 0 in LOC.

    T$ is printed at the menu's top,
in reverse, between HOME and UP. B$ is
printed at the bottom, between QUIT
and DOWN. You needn't use the actual
variables T$ and B$, but if this is
going to be a file requestor, it's
perfect. The user gets to see the disk
name and blocks free without any extra
effort from you.

    There is no way to customize the
scrolling menu. Auto-caging and
point-to-first are mandatory.

    Set W to 255 and the proper width
for a file requestor will be assigned,
but that's it. DB+ knows what filename
info looks like and will set F$
properly when it finds a filename -
regardless of width.

    NOTE: Using the SCROLLING MENU
with a location in LOC changes what
the RACK INDEX routine is cued up to
read and removes any sorting.


  CHARACTER SWAP
  --------------
    Include: .CHRSWP
  .CHRSWP,SEEK,REPLACE,COLOR

    This small routine scans the
screen for a specific screen code, and
replaces it with the given screen
code, with the given color. A color of
128 causes only the characters to be
changed, not their colors.


  COLOR SWAP
  ----------
    Include: .COLSWP
  .COLSWP,SEEK,REPLACE

    This routine finds all instances
of a specific color and replaces them
with the given color. Screen memory is
not affected.


  MORE ABOUT INDEXING
  -------------------

    When a file is RACKed up by
yourself or a scrolling menu, MV+24/25
reveal the location of the text's
newly generated pointers. The number
of items in the current INDEXable file
is at MV+26/27. These two variables
are at the disposal of the advanced
programmer.

    By preserving and later restoring
MV+24-27, it is possible have two or
more INDEXable files in memory at
once, without having to RACK them
(taking almost a second) just so you
can switch between them.

    RACKing also would wipe out all
the "selected" flags stored as bit 7
of each item's LENGTH value (by
.MSMENU). You may want to preseve
MV+24-27 before calling another
scrolling menu so you do not lose
these flags. POKE the saved values
back into MV+24-27 when it's time to
INDEX SELECTED ITEMs.

    Yes sir. We have multi-selectable
scrolling menus now! Hang on!

     X+128 enables a powerful new
feature. If you do not like the
generic look of the scrolling menu,
you can now do something about it!

    Several things DON'T happen when
x+128 is used. The bx,ic,t$, and b$
parameters are IGNORED. The scrolling
menu is NOT drawn. The CAGE remains
unchanged. The X,Y,W,H parameters now
represent the area for the ACTUAL
scrolling text alone.

     "Manual Icons" means just that.
DB+ is trusting YOU to create, label,
and enable (as regions) the icons for
your scrolling menu. They can be any
size and at any location.

    Since you may not always label the
EXIT icon as "Quit", MV+16 exists so
you can assign an appropriate key to
the exit function. The CRSR keys still
scroll and page, and HOME still goes
home. ESCAPE cancels, just like EXIT
(in the regular scrolling menu).

    MULTI-SELECT SCROLL MENUs need two
additional parameters, S and W.

.MSMENU,X,Y,W,H,bx,ic,u,h,s,w,l,t$,b$

    The confusing letters are mostly
COLORs and read like this:

    Box
    Icons
    Un-highlight
    Highlight
    Selected
    (selected) With bar
    Location

    It's always easy to spot the
selected items, even when they are
under the highlight bar. Which of the
u,h,s,w items are REVERSED is set from
bits 3-0 to MV+15. By default, the
highlight bar and all selected items
are reversed. Each reverse bit can be
temporarily disobeyed by adding 128 to
the u,h,s,w parameters.

    Selecting items is as easy as
hitting RETURN or clicking on them.
The item is toggled and the mouse and
highlight bar are moved down to the
next item, scrolling when necessary -
even when selecting with the mouse!

    The additional keys A, N, and T
function within multi-select menus to
select ALL, NONE, and to TOGGLE ALL
items (respectively). The mouse user
cannot access these special features
unless YOU enable manual icons!

    Exiting a multi-select menu is the
confusing part. If you press the EXIT
key (MV+16), SL% will return the
number of items selected. If ESCAPE is
pressed, the menu is cancelled and
zero is returned in SL%. The selected
items still exist, and still can be
indexed, but you are just told that
there weren't any selected items.

    If you are using manual icons, the
mouse usually can move anywhere on the
screen. Nothing happens if the user
clicks outside the menu. Even clicking
on an active region has no effect IF
the region number isn't one to which
we have assigned a function.

    Here are the REGION NUMBERS and
the functions they would have for a
regular scrolling menu:

     1. home
     2. scroll up
     3. scroll down
     4. exit
     5. page up
     6. page down

     Regions 5 and 6 aren't
necessary, so don't feel obligated to
use them. Nothing bad will happen if
you don't have 6 active regions.
Right-clicking on regions 2 and 3
also PAGE, too.

    MULTI-SELECT SCROLL MENUs will
obey up to four extra regions, if you
take the time to define them.

     7. select all
     8. select none
     9. toggle all
    10. cancel

    Pressing EXIT or clicking on
region 4 will return the number of
selected items in SL%. Region 10
behaves just like ESCAPE, returning a
grand total of zero selected items.

    Remember: When regions overlap,
the higher number has priority. So, if
you don't want regions 5 and 6 in your
multi-select menu, just be sure to
define regions 7 and 8 so they
perfectly overlap the previous two!

    However, joystick users with a
repeating fire button may appreciate
regions 5 and 6. No matter what you
decide, be sure to include regions
1-4: the same ones that are present
using the generic "standard" icons.


 STAY TUNED!
 -----------

    There's more fun in Part IV!

 DMM/LN